Add documentation on top of rustc_middle/src/query/mod.rs
#142450
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
r? @SparrowLii rustbot has assigned @SparrowLii. Use |
rustbot
added
S-waiting-on-review
xizheyin
force-pushed
the
rustc-query-doc
branch
2 times, most recently
from
7b757e3 to
a7220f3
Compare
xizheyin
commented
Jun 13, 2025
Comment on lines
8
to
22
| //! ## How to Read This Module | ||
| //! | ||
| //! Each `query` block in this file defines a single query, specifying its key and value types, along with various modifiers. | ||
| //! These query definitions are processed by the macro system, which expands them into the necessary boilerplate code | ||
| //! for the query system—including the [`Providers`] struct (a function table for all query implementations, where each field is | ||
| //! a function pointer to the actual provider), caching, and dependency graph integration. | ||
| //! **Note:** The `Providers` struct is not a Rust trait, but a struct generated by the macro system to hold all provider functions. | ||
| //! The macro system also supports a set of **query modifiers** (see below) that control the behavior of each query. | ||
| //! | ||
| //! The actual provider functions are implemented in various modules and registered into the `Providers` struct | ||
| //! during compiler initialization (see [`rustc_interface::passes::DEFAULT_QUERY_PROVIDERS`]). | ||
| //! | ||
| //! [`rustc_interface::passes::DEFAULT_QUERY_PROVIDERS`]: ../../rustc_interface/passes/static.DEFAULT_QUERY_PROVIDERS.html | ||
| //! |
There was a problem hiding this comment.
I restructured it to focus on interpreting the code, focusing on the core structure of Providers, which is a good place to start in understanding this module.
There was a problem hiding this comment.
rustc macros is better than macro systems here. Others looks fine.
|
The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes. |
xizheyin
force-pushed
the
rustc-query-doc
branch
from
d1390f9 to
a7220f3
Compare
|
r=me after fixing the nits |
|
✌️ @xizheyin, you can now approve this pull request! If @SparrowLii told you to " |
Signed-off-by: xizheyin <xizheyin@smail.nju.edu.cn>
xizheyin
force-pushed
the
rustc-query-doc
branch
from
a7220f3 to
ade2ad9
Compare
|
CI has passed. |
bors
added
S-waiting-on-bors
Kobzol
added a commit
to Kobzol/rust
that referenced
this pull request
Jun 16, 2025
…wLii
Add documentation on top of `rustc_middle/src/query/mod.rs`
The `rustc-dev-guide` gives a high-level intro, but many details—especially about how the code works and modifiers in `query xxx(){...}`—are only in code comments or the macro implementation. This doc makes it easier for contributors and code readers to understand the workflow and available modifiers without jumping between files and docs.
This PR adds a comprehensive module-level doc comment to `rustc_middle::query::mod.rs` that:
1. Provides an overview of the query system and macro-based query definitions for reading code more easily
2. Centralizes documentation for all query modifiers (previously scattered or only in `rustc_macro` code), closely following the authoritative list in QueryModifiers.
bors
added a commit
that referenced
this pull request
Jun 16, 2025
Rollup of 12 pull requests Successful merges: - #141639 (Expose discriminant values in stable_mir) - #142082 (Refactor `rustc_attr_data_structures` documentation) - #142125 (Stabilize "file_lock" feature) - #142236 (Add documentation for `PathBuf`'s `FromIterator` and `Extend` impls) - #142373 (Fix Debug for Location) - #142416 (Assorted bootstrap cleanups (step 2)) - #142431 (Add initial version of snapshot tests to bootstrap) - #142450 (Add documentation on top of `rustc_middle/src/query/mod.rs`) - #142528 (clarify `rustc_do_not_const_check` comment) - #142530 (use `if let` guards where possible) - #142561 (Remove an `njn:` comment accidentaly left behind.) - #142566 (Fix `-nopt` CI jobs) r? `@ghost` `@rustbot` modify labels: rollup
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The
rustc-dev-guidegives a high-level intro, but many details—especially about how the code works and modifiers inquery xxx(){...}—are only in code comments or the macro implementation. This doc makes it easier for contributors and code readers to understand the workflow and available modifiers without jumping between files and docs.This PR adds a comprehensive module-level doc comment to
rustc_middle::query::mod.rsthat:rustc_macrocode), closely following the authoritative list in QueryModifiers.